iT邦幫忙

2023 iThome 鐵人賽

DAY 4
0
Modern Web

FastAPI 入門30天系列 第 4

Day-4 路徑參數與查詢參數

  • 分享至 

  • xImage
  •  

在設計API中,肯定會碰到需要傳入參數的時候。

舉個例子,我們使用點餐系統作為範例,實作API時,拿取一張訂單可能會設計為 /order/1 或者是 /order/?id=1

前者直接將值放置在路徑中的稱為路徑參數,後者為key-value的集合,位於URL的?後面並以&

隔開,我們稱為查詢參數。

接下來我們接續上一章 HelloWorld 的程式碼繼續使用。

路徑參數

在FastAPI中,你可以使用跟Python f-string 一樣的語法來宣告路徑參數。

@app.get("/orders/{id}")
def get_order(id: int):
    return {"id": id, "name": "My order"}

我們在路徑中宣告要傳入參數 id,並將參數傳遞給 get_order 函式。

在 get_order 函式的輸入定義id的型態為 int,FastAPI會自動幫你驗證輸入的是不是 int。

在文件畫面也會跟你說這個路徑參數需要傳入 int

https://ithelp.ithome.com.tw/upload/images/20230909/20152669b5HcxDPth4.png

正確輸入會得到以下 response。

https://ithelp.ithome.com.tw/upload/images/20230909/20152669UZXZFjSGep.png

若輸入 int 以外的會發生驗證錯誤。

https://ithelp.ithome.com.tw/upload/images/20230909/20152669s5QgM3vKrS.png

查詢參數

除了路徑參數以外,在函式中宣告的輸入參數都會被認為是查詢參數。

@app.get("/orders")
def get_order(id: int):
    return {"id": id, "name": "My order"}

我們只定義 get_order 需要一個 int 型態的 id 輸入,這樣便會被自動解析為是要傳入查詢參數。

在API文件中也可以看到確實如我們所要 :

https://ithelp.ithome.com.tw/upload/images/20230909/20152669nJ8CKp13Ki.png

測試看看會獲得以下結果

https://ithelp.ithome.com.tw/upload/images/20230909/20152669s9yARfuDxf.png

選填和預設值

由於查詢參數不是API路徑的固定部分,所以可以設置為選填並可有預設值。

@app.get("/orders")
def get_order(id: int = 5):
    return {"id": id, "name": "My order"}

只需要在函式輸入定義好給予的值即可,這裡預設為 5 。

https://ithelp.ithome.com.tw/upload/images/20230909/20152669uPQXzhxRoO.png

在API文件中可以看到 id 變為選填,且 default value 為 5。

你也可以將一個參數的型態設為 {type} | None 的形式,並將預設值給予 None,以達成選填效果。

@app.get("/orders")
def get_order(id: int = 5, q: str | None = None):
    if q:
        return {"id": id, "name": q}
    return {"id": id, "name": "My order"}

並在程式判斷參數存不存在,以執行對應邏輯。

混合參數使用

FastAPI允許將兩種參數混合使用,只需要宣告定義好即可。

@app.get("/user/{user_id}/order/{order_id}")
def get_user_order(user_id: int, order_id: int, q: str | None = None):
    return {"user_id": user_id, "order_id": order_id, "q": q}

例如以上 user_id, order_id 皆為路徑參數,q 為查詢參數,FastAPI皆可解析的到。

https://ithelp.ithome.com.tw/upload/images/20230909/20152669DheJJGpG57.png

文件中可以看到,被解析分類成我們想要的形式。

小結

透過今天的介紹,大家應該知道如果要實作一個 get 端點時我們要怎麼讓用戶端去輸入我們需要的參數了,FastAPI 在解析路徑和查詢參數的同時還能夠順便驗證資料型別,我覺得這是一個十分便利的事情。

參考資料

路径参数 - FastAPI (tiangolo.com)

查询参数 - FastAPI (tiangolo.com)


上一篇
Day-3 FastAPI的 HelloWorld
下一篇
Day-5 在Request Body中的參數
系列文
FastAPI 入門30天30
圖片
  直播研討會
圖片
{{ item.channelVendor }} {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言